home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / mac / developm / source / drgnsmth.cpt / Dragonsmith 1.1 / Documentation / Preferences class notes < prev   
Encoding:
Text File  |  1992-10-11  |  2.2 KB  |  46 lines
  1.  
  2. Preferences class notes
  3. ----------------------
  4.  
  5. by Paul Hoffman
  6. Internet:    paul.hoffman@um.cc.umich.edu
  7.  
  8. This class is provided as part of Dragonsmith 1.1 but can be used by any application developed with THINK C.
  9.  
  10. Features
  11. --------
  12. The Preferences class provides simple resource-based preferences management, allowing an application to easily implement a standard preferences file.  The class is reasonably failure-tolerant -- with a modicum of defensive programming, an application can function regardless of whether a preferences file was created or any particular preference resource was found.
  13.  
  14. Implementation
  15. --------------
  16. The various preferences resources are referenced by a single 'PrRo' 128 ("preferences roster") resource that will be copied from the application file to a newly created preferences file.  Each preferences resource is designated by the index of its entry in this resource.
  17.  
  18. An application which uses an object of this class should do something like this in its initialization code, while the application file is still the most recently opened resources file:
  19.  
  20.         #define prefsFileType 'pref'        // This is the recommended value (see Preferences.h)
  21.  
  22.         prefsObject = new Preferences;
  23.         appResFork = CurResFile();
  24.         allOK = prefsObject->Init(appResFork, appSignature, prefsFileType);
  25.  
  26.         // Here, find the preferences file and store an FSSpec to it in prefsFileSpec
  27.  
  28.         if (allOK)
  29.                 allOK = preferences->UseFile (&prefsFileSpec);
  30.  
  31. A particular preferences resource can then be obtained by calling
  32.         prefsObject->GetPref(prefIndex);
  33. where prefIndex is the desired preference's index within the 'PrRo' 128 resource.
  34.  
  35. The resource can then be treated like any other resource, except that you must NOT  ReleaseResource or DetachResource it -- call
  36.         prefsObject->DetachPrefResource(prefIndex)
  37. and
  38.         prefsObject->ReleasePrefResource(prefIndex)
  39. instead, or serious problems may occur later!
  40.  
  41. If the user double-clicks on a preferences file belonging to your application, you can just call
  42.         allOK = preferences->UseFile(&theFileSpec);
  43. and read in the preferences if it succeeds.
  44.  
  45. See the Dragon.c file in the Dragonsmith 1.1 release for an example of how to use the Preferences class -- especially, how to locate the application's preferences file.
  46.